.. _`Organizations`: https://developer.kontur.ru/doc/extern/method?type=get&path=%2Fv1%2F%7BaccountId%7D%2Forganizations
.. _`GET Organizations`: https://developer.kontur.ru/doc/extern/method?type=get&path=%2Fv1%2F%7BaccountId%7D%2Forganizations
.. _`POST Organization`: https://developer.kontur.ru/doc/extern/method?type=post&path=%2Fv1%2F%7BaccountId%7D%2Forganizations
.. _`PUT Organization`: https://developer.kontur.ru/doc/extern/method?type=put&path=%2Fv1%2F%7BaccountId%7D%2Forganizations%2F%7BorgId%7D
.. _`GET Organization`: https://developer.kontur.ru/doc/extern/method?type=get&path=%2Fv1%2F%7BaccountId%7D%2Forganizations%2F%7BorgId%7D
.. _`DELETE Organization`: https://developer.kontur.ru/doc/extern/method?type=delete&path=%2Fv1%2F%7BaccountId%7D%2Forganizations%2F%7BorgId%7D
.. _`POST UpdateSigner`: https://developer.kontur.ru/doc/extern/method?type=post&path=%2Fv1%2F%7BaccountId%7D%2Forganizations%2F%7BorgId%7D%2Fupdate-signer
.. _`POST ControlUnitSubscriptions`: https://developer.kontur.ru/doc/extern/method?type=post&path=%2Fv1%2F%7BaccountId%7D%2Forganizations%2F%7BorgId%7D%2Fcontrol-unit-subscriptions
.. _`POST Gosuslugi Auth`: https://developer.kontur.ru/doc/extern/method?type=post&path=%2Fv1%2F%7BaccountId%7D%2Forganizations%2F%7BorgId%7D%2Fgosuslugi-auth

Методы для работы с организациями
=================================

В данном разделе пойдет речь о работе с организациями в указанной учетной записи. 

Подробная спецификация методов показана в сваггере в разделе Organizations_.

Список доступных методов:

* `Получение списка доступных организаций`_
* `Получение организации по ее идентификатору`_
* `Добавление организации`_
* `Установка подписанта`_
* `Поиск подписок на контролирующие органы`_
* `Редактирование организации`_
* `Удаление организации`_
* `Авторизация на Госуслугах`_

Получение списка доступных организаций
--------------------------------------

Метод: `GET Organizations`_

Метод используется для получения списка всех организаций, за которые возможна работа из-под указанной учетной записи. 

.. _rst-markup-organization:

Получение организации по ее идентификатору
------------------------------------------

Метод: `GET Organization`_ 

Метод вернет основные сведения об организации по ее идентификатору ``orgId``. В ответе вернется актуальная информация о контролирующих органах и подписантах для каждого из них. 

Добавление организации
----------------------

Метод: `POST Organization`_

Метод позволяет добавить новую организацию в учетную запись Контур.Экстерна.

В рамках :ref:`многопользовательского режима<rst-markup-mpr>` администратор может добавить организацию для всех пользователей. Дополнительный пользователь, при наличии прав доступа, может добавить организацию в учетную запись. Если операция завершилась успешно, то организация появится и у пользователя, и у администратора. Количество организаций определяется тарифным планом.

Установка подписанта
--------------------

Метод: `POST UpdateSigner`_

С помощью метода можно выбрать сертификат для подписи и тип подписанта для отчетности в один из контролирующих органов. 

Поиск подписок на контролирующие органы
---------------------------------------

Метод: `POST ControlUnitSubscriptions`_

Метод вернет информацию о подписках на контролирующие органы организации по ее идентификатору.

Редактирование организации
--------------------------

Метод: `PUT Organization`_

Допускается изменение только названия организации.

Удаление организации
--------------------

Метод: `DELETE Organization`_

Метод позволяет удалить организацию из учетной записи Контур.Экстерна.

Организацию можно удалить при следующих условиях:

* если прошло больше 12 месяцев со дня регистрации организации в Контур.Экстерн;
* если прошло меньше 12 месяцев со дня регистрации организации, но в текущем отчетном периоде не отправлялись отчеты, письма и запросы в контролирующие органы;
* если организация ликвидирована по данным ЕГРЮЛ.

В рамках :ref:`многопользовательского режима<rst-markup-mpr>` администратор может удалить организацию из структуры для всех пользователей. Дополнительный пользователь может удалить организацию только у себя.

.. _rst-markup-gosuslugiauth:

Авторизация на Госуслугах
-------------------------

Метод `POST Gosuslugi Auth`_

Метод получает токен доступа для указанной организации. API Контур.Экстерна сохраняет его для передачи в следующих запроса к API Госуслуг. Это нужно для отправки уведомлений в МВД.

**Тело запроса**

* ``gosuslugi-uid`` — API-ключ сотрудника из Госуслуг.
* ``base64-signature-content`` — файл подписи API-ключа в формате base64.

**Как создать файл подписи**

    1. Создайте файл с расширением .txt в формате UTF-8 без BOM. Например, api_key.txt.
    2. Скопируйте в файл API-ключ сотрудника и сохраните его.
    3. Выполните подписание для создания открепленной подписи в формате PKCS#7 с расширением .p7s. Сертификат для подписания должен включать ИНН организации, на сотрудника которой выдан API-ключ.
    4. Сконвертируйте полученный файл подписи в формат base64 и укажите его в теле запроса. Срок жизни файла подписи после отправки запроса составляет 18 часов.